MODULE = PlPN          PACKAGE = PlPN::DocumentEventSink

#
# this package doesn't used the standard XS/C++ interface
# because the object is a boost shared_ptr, not a real pointer
#

#
# Pod::Html is kind of brain-dead:
#
# Place Z<> between function names and parentheses, otherwise Pod::Html
# assumes you meant to put C<...> around it
#
# Put explicit text in all links L<use my text, stupid|some::perl::module>,
# otherwise Pod::Html assumes you want "the X manpage". (Does not apply to
# relative links withing this file.)
#
# It also assumes you want a link if you have C<...> with text matching a
# potential link target. The only way I've found around that is to split it
# up into multiple pieces: C<wo>C<rd>. Looks correct in the resulting HTML,
# but it's ugly to have <code>wo</code><code>rd</code> in the source, and I
# shouldn't have to do it.
#

=head1 NAME

PlPN::DocumentEventSink - The document event sink

=head1 SYNOPSIS

	{
		package MyDocumentEventSinkWithUniqueClassName;
		use PlPN;
		our @ISA = qw(PlPN::DocumentEventSink);
		
		sub OnSchemeChange {
			# do something
		}
		
		# etc.
	} # scope ends; return to original package
	
	use PlPN qw(PN);
	
	my $docsink = new MyDocumentEventSinkWithUniqueClassName;
	$some_doc->AddEventSink($docsink);
	
	# etc.

=head1 DESCRIPTION

Catches document events from Programmer's Notepad documents.

The default constructor simply blesses an empty hashref into the class.

The default events do nothing; they exist so that derived classes can omit
them without causing Perl to crash when C++ code tries to call the event.

The document object is always passed as the first parameter of an event;
this allows the same document sink to be used with multiple documents.

=head1 EVENTS

=over

=item OnSchemeChangeZ<>($doc, $scheme)

=item OnDocClosingX<>($doc)

=item OnAfterLoadZ<>($doc)

=item OnBeforeSaveZ<>($doc, $filename)

=item OnAfterSaveZ<>($doc)

=item OnModifiedChangedZ<>($doc)

=item OnWriteProtectChangedZ<>($doc)

See L<PlPN::RegisterEvent|PlPN/RegisterEvent> for descriptions of these
events.

=back

=head1 COPYRIGHT and LICENCE

Copyright (c) 2012 Sean Healy. All rights reserved.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

=cut

SV*
new(CLASS)
		const char* CLASS;
	CODE:
		HV* hv = newHV();
		RETVAL = newRV_noinc((SV*)hv);
		sv_bless(
			RETVAL,					/* reference to be blessed */
			gv_stashpv(CLASS, 1)	/* stash to bless it into */
		);
	OUTPUT:
		RETVAL

# we shouldn't need a DESTROY

void
OnSchemeChange(...)
	CODE:
		// default implementation so we don't croak for lack of a method

void
OnDocClosing(...)
	CODE:
		// default implementation so we don't croak for lack of a method

void
OnAfterLoad(...)
	CODE:
		// default implementation so we don't croak for lack of a method

void
OnBeforeSave(...)
	CODE:
		// default implementation so we don't croak for lack of a method

void
OnAfterSave(...)
	CODE:
		// default implementation so we don't croak for lack of a method

void
OnModifiedChanged(...)
	CODE:
		// default implementation so we don't croak for lack of a method

void
OnWriteProtectChanged(...)
	CODE:
		// default implementation so we don't croak for lack of a method
